Skip to content

Correct wheel naming when targeting iOS#2827

Merged
messense merged 1 commit intoPyO3:mainfrom
freakboy3742:ios-wheel-naming
Nov 7, 2025
Merged

Correct wheel naming when targeting iOS#2827
messense merged 1 commit intoPyO3:mainfrom
freakboy3742:ios-wheel-naming

Conversation

@freakboy3742
Copy link
Copy Markdown
Contributor

@freakboy3742 freakboy3742 commented Nov 7, 2025

At present, when targeting iOS, Maturin produces a wheel using Unix-style naming based on the Darwin kernel version.

PEP 730 defined the standard for tagging binary wheels for iOS. This standard has been ratified by the Python Steering Council, and has been integrated into pip and PyPI/Warehouse.

  • ios_X_Y_arm64-iphoneos for iOS devices, matching Rust's aarch64-apple-ios target
  • ios_X_Y_arm64_iphonesimulator for iOS devices, matching Rust's aarch64-apple-ios-sim target
  • ios_X_Y_x86_64_iphonesimulator for iOS devices, matching Rust's x86_64-apple-ios target

where X_Y is the minimum supported iOS version for the wheel. This is managed by the IPHONEOS_DEPLOYMENT_VERSION environment variable; it has similar semantics to MACOSX_DEPLOYMENT_VERSION and the version number in macOS wheels.

This PR modifies the wheel names generated by Maturin when targeting an iOS platform to match PEP 730 expectations, and modifies PyPI tests to reflect the validity of iOS wheels.

Copy link
Copy Markdown
Member

@messense messense left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@messense messense merged commit fda29ee into PyO3:main Nov 7, 2025
43 checks passed
@messense messense linked an issue Nov 7, 2025 that may be closed by this pull request
2 tasks
@freakboy3742 freakboy3742 deleted the ios-wheel-naming branch November 7, 2025 08:50
messense pushed a commit that referenced this pull request Nov 7, 2025
Tools such as `cibuildwheel` and
[`xbuild`](https://pypi.org/project/xbuild/) manage building wheels for
iOS by using a cross-platform virtual environment - a valid virtual
environment for the build platform that can "pretend" to be the
target/host platform when asked for sysconfigdata. This is done by
monkeypatching key values in the sys, sysconfig, platform and os module
when the interpreter starts. Many of these environments also set
`sys.cross_compiling = True` as an indicator that they aren't "real"
environments.

Maturin's concept of "cross-compiling", however, has more to do with
whether the interpreter that is running the Maturin build can be used to
interrogate details about the Python install for the purpose of
configuring a build. To that end, somewhat counterintuitively, a
cross-platform venv *isn't* "cross platform" from the perspective of
Maturin.

This PR makes 3 changes:
1. It marks iOS builds as *not* being cross-platform. This ensures that
the sysconfigdata values from the interpreter running maturin are passed
to the build
2. When the build has not been given an explicit `--target`, or
`--interpreter`, the build interpreter will be interrogated to see if it
is a cross-compilation environment - and if it is, the target implied by
the platform is used for the build.
3. When an explicit `--interpreter` *has* been provided, the target will
be modified if the environment is a cross-platform environment.

When combined with #2827, this means it is possible to create an iOS
wheel with no more than `maturin build`, provided you're in an iOS
cross-platform venv (such as those created by `cibuildwheel` and
`xbuild`).
messense pushed a commit that referenced this pull request Nov 10, 2025
At present, when targeting an `abi3` build, Maturin will use a dummy
interpreter to provide build configuration details, unless the user
specifies an interpreter with `--interpreter`, or the target is
cross-compiling, or Windows is being targeted.

The use of a dummy interpreter when a real interpreter is available can
lead to the interpreter details that are available and defined in
`sysconfigdata` not being used as part of the build process.

This was discovered in the process of working on iOS support (see #2827
and #2828); although the iOS build environment *does* provide build
configuration details, those details were not being passed down to the
PyO3 build configuration. With those two patches (and some patches to
PyO3 - see PyO3/pyo3#5605 and PyO3/pyo3#5606), it was possible to build
a non-abi3 wheel; but this patch was needed to build an abi3 wheel.
messense pushed a commit that referenced this pull request Nov 13, 2025
#2827 introduced PEP 730-compilant tags for iOS wheels. 

The PR description for that ticket correctly described the tags that
*should* exist; but due to the inconsistent naming of the Rust
`x86_64-apple-ios` *simulator* target, the implementation in #2827 would
produce wheels tagged `x86_64_iphoneos`.

This PR corrects that oversight.
messense pushed a commit that referenced this pull request Nov 19, 2025
#2827 introduced PEP 730-compilant tags for iOS wheels. 

The PR description for that ticket correctly described the tags that
*should* exist; but due to the inconsistent naming of the Rust
`x86_64-apple-ios` *simulator* target, the implementation in #2827 would
produce wheels tagged `x86_64_iphoneos`.

This PR corrects that oversight.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve iOS target support

2 participants